<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>libnetconf: NETCONF library - libnetconf</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="cesnet-logo-125.png"/></td>
  <td style="padding-left: 0.5em;">
   <div id="projectname">libnetconf
   &#160;<span id="projectnumber">0.1.4</span>
   </div>
   <div id="projectbrief">NETCONF library</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li class="current"><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="pages.html"><span>Related&#160;Pages</span></a></li>
      <li><a href="modules.html"><span>Modules</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('index.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">NETCONF library - libnetconf </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>This documents provides documentation of the NETCONF library (libnetconf).</p>
<h2>CLIENT WORKFLOW</h2>
<p>Here is a description of using libnetconf functions in a NETCONF client:</p>
<ol type="1">
<li><b>Set verbosity (optional)</b>.<br/>
 The verbosity of the libnetconf can be set by <a class="el" href="d3/d35/group__gen_a_p_i.html#gadd8fd7b3bb2e7cba580c9a4229fe02d7" title="Set libnetconf&#39;s verbosity level.">nc_verbosity()</a>. By default, libnetconf is completely silent.<br/>
 There is a default message printing function writing messages on the stderr. The application's specific message printing function can be set via <a class="el" href="d3/d35/group__gen_a_p_i.html#ga806dfa9c27d2b8076bae21bcd549cce7" title="Set callback function for printing libnetconf&#39;s messages.">nc_callback_print()</a> function.</li>
<li><b>Set SSH authentication methods priorities (optional)</b>.<br/>
 libnetconf supports several SSH authentication methods for connecting with a NETCONF server over SSH. However, the used method is selected from the list of supported authentication methods provided by the server. Client is allowed to specify the priority of each supported authentication method via <a class="el" href="db/d52/group__session.html#ga13119fdaa84544bf254bdb35ffdf83e0" title="Set preference of the SSH authentication methods.">nc_ssh_pref()</a> function. The authentication method can be also disabled using a negative priority value.<br/>
 Default priorities are as following:<ul>
<li><em>Interactive</em> (value 3)</li>
<li><em>Password</em> (value 2)</li>
<li><em>Public keys</em> (value 1)</li>
</ul>
</li>
<li><b>Set own callback(s) for the SSH authentication methods (optional)</b>.<br/>
 User credentials are get via callback functions specific for each authentication method. There are default callbacks, but application can set their own via:<ul>
<li><em>Interactive</em> - <a class="el" href="db/d52/group__session.html#gacb6042fe2f3cfe5d79e01de599c546eb" title="Set callback function for passing user credentials into libssh2&#39;s keyboard-interactive authentication...">nc_callback_sshauth_interactive()</a></li>
<li><em>Password</em> - <a class="el" href="db/d52/group__session.html#ga28299d575ef4e234ed96bad5c4f086fb" title="Set callback function for passing user password into libssh2&#39;s password authentication method when co...">nc_callback_sshauth_password()</a></li>
<li><em>Publuc keys</em> - <a class="el" href="db/d52/group__session.html#ga81ef9b1c1949bbffd86cbfd9aa159726" title="Set callback function for passing user password into libssh2&#39;s publickey authentication method when c...">nc_callback_sshauth_passphrase()</a>. Here, also paths to the key files can be specified by nc_set_publickey_path() and nc_set_privatekey_path(). If not set, libnetconf tries to find them in default paths.</li>
</ul>
</li>
<li><b>Connect to the NETCONF server(s)</b>.<br/>
 Simply call <a class="el" href="db/d52/group__session.html#gae3858d998d19cb2fb700b15fdf602f23" title="Create NETCONF session to the specified server.">nc_session_connect()</a> to connect to the specified host via SSH. Authentication method is selected according to default values or previous steps.</li>
<li><b>Prepare NETCONF rpc message(s)</b>.<br/>
 Creating NETCONF rpc messages is covered by functions described in section <a class="el" href="db/de9/group__rpc.html">NETCONF rpc</a>. Application prepares NETCONF rpc messages according to specified attributes. These messages can be then repeatedly used for communication over any of the created NETCONF sessions.</li>
<li><b>Send the message to the selected NETCONF server</b>.<br/>
 To send created NETCONF rpc message to the NETCONF server, use <a class="el" href="db/de9/group__rpc.html#ga5e74aefb070caa3437a4a2312c3dfc84" title="Send &lt;rpc&gt; request via specified NETCONF session. This function is supposed to be performed only by N...">nc_session_send_rpc()</a> function. <a class="el" href="db/de9/group__rpc.html#ga19f68212e621d7b556ee9e60ec71dc7a" title="Send &lt;rpc&gt; and receive &lt;rpc-reply&gt; via the specified NETCONF session.">nc_session_send_recv()</a> function connect sending and receiving the reply (see next step) into one blocking call.</li>
<li><b>Get the server's rpc-reply message</b>. When the NETCONF rpc is sent, use <a class="el" href="d0/de2/group__reply.html#ga4bbbfc4e648a74caffeeac0da41ab276" title="Receive &lt;rpc-reply&gt; response from the specified NETCONF session. This function is supposed to be perf...">nc_session_recv_reply()</a> to receive the reply. To get know when the reply is coming, file descriptor of the communication channel can be checked by poll(), select(), ... This descriptor can be obtained via <a class="el" href="db/d52/group__session.html#ga826890ed745633bc2d31a53971dada32" title="Get input file descriptor to asynchronous control of input events.">nc_session_get_eventfd()</a> function.</li>
<li><b>Close the NETCONF session</b>.<br/>
 When the communication is finnished, the NETCONF session is closed by <a class="el" href="db/d52/group__session.html#ga20b9940ed7af543a05b4bef6e871cedd" title="Close NETCONF connection with the server.">nc_session_close()</a> and all used structures are freed by <a class="el" href="db/d52/group__session.html#gaa5994f45a7031dc931bdf4a3acebedee" title="Cleanup the session structure and free all allocated resources.">nc_session_free()</a>.</li>
<li><b>Free all created objects</b>.<br/>
 Do not forget to free created rpc messages (<a class="el" href="db/de9/group__rpc.html#ga4041bda37caa9eedb7a1e2534280f3df" title="Free rpc message.">nc_rpc_free()</a>), <a class="el" href="db/de9/group__rpc.html#ga3212b7af605b6bdf83b893979c3bcc79">filters</a> (<a class="el" href="db/de9/group__rpc.html#ga0dbfd598d6fd303819817370cdf63229" title="Destroy filter structure.">nc_filter_free()</a>) or received NETCONF rpc-replies (<a class="el" href="d0/de2/group__reply.html#ga17aa9f38d7b75dec1a57b478b0b39710" title="Free reply message.">nc_reply_free()</a>).</li>
</ol>
<h2>SERVER ARCHITECTURE</h2>
<p>There are two basic approaches how to implement NETCONF server using libnetconf.</p>
<h3>Single-level Architecture</h3>
<div class="image">
<img src="../../img/sl_arch.png"  alt="Single-level architecture" title="Single-level architecture"/>
</div>
<p>In this case, all server functionality is implemented as a single process. It is started by SSH daemon as its Subsystem for each incoming NETCONF session connection. The main issue of this approach is a simultaneous access to the shared resources. Device manager has to solve concurrent access to the controlled device from its multiple instances. libnetconf itself has to deal with simultaneous access of shared configuration datastore.</p>
<h3>Multi-level Architecture</h3>
<div class="image">
<img src="../../img/ml_arch.png"  alt="Multi-level architecture" title="Multi-level architecture"/>
</div>
<p>In the second case, there is only one device manager (NETCONF server) running as a system daemon. This solves the problem of concurrent device access from multiple processes. On the other hand, there is a need of inter-process communication between the device manager and agents launched as the SSH Subsystems. These agents hold NETCONF sessions and receive requests from the clients. libnetconf provides functions (<a class="el" href="db/de9/group__rpc.html#ga3e840368c40be2ea4d5201edbd3adaca" title="Dump the rpc message into a string.">nc_rpc_dump()</a> and <a class="el" href="db/de9/group__rpc.html#ga16bda6ae6ad26653e8793abf58ebec2b" title="Build &lt;rpc&gt; message from the string. This is the reverse function of the nc_rpc_dump().">nc_rpc_build()</a>) to (de-)serialise content of the NETCONF messages. This allows to pass the NETCONF messages between agent and device manager that applies requests to the operated device and a configuration datastore.</p>
<h2>SERVER WORKFLOW</h2>
<p>Here is a description of using libnetconf functions in a NETCONF server. According to used architecture, the workflow can be split between agent and server. For this purpose, functions <a class="el" href="db/de9/group__rpc.html#ga3e840368c40be2ea4d5201edbd3adaca" title="Dump the rpc message into a string.">nc_rpc_dump()</a>, <a class="el" href="db/de9/group__rpc.html#ga16bda6ae6ad26653e8793abf58ebec2b" title="Build &lt;rpc&gt; message from the string. This is the reverse function of the nc_rpc_dump().">nc_rpc_build()</a> and <a class="el" href="db/d52/group__session.html#gad821a04ee9dc04bbed04ea1d138afbed" title="Create disconnected session structure.">nc_session_dummy()</a> can be very helpful.</p>
<ol type="1">
<li><b>Set verbosity (optional)</b>.<br/>
 The verbosity of the libnetconf can be set by <a class="el" href="d3/d35/group__gen_a_p_i.html#gadd8fd7b3bb2e7cba580c9a4229fe02d7" title="Set libnetconf&#39;s verbosity level.">nc_verbosity()</a>. By default, libnetconf is completely silent.<br/>
 There is a default message printing function writing messages on the stderr. On the server side, this is not very useful, since server usually runs as a daemon without stderr. In this case, something like syslog should be used. The application's specific message printing function can be set via <a class="el" href="d3/d35/group__gen_a_p_i.html#ga806dfa9c27d2b8076bae21bcd549cce7" title="Set callback function for printing libnetconf&#39;s messages.">nc_callback_print()</a> function.</li>
<li><b>Initiate datastore</b>.<br/>
 As the first step, create datastore handle using ncdsd_new() with specific datastore type implementation. Optionally, some implementation type specific parameters can be set (e.g. <a class="el" href="db/d67/group__store.html#gad48955dab497b1258d80019e542acb9b" title="Assign path of the datastore file into the datastore structure.">ncds_file_set_path()</a>). Finally, init datastore using <a class="el" href="db/d67/group__store.html#gaabb1ae2c497726ad826fc6478f97e8ff" title="Activate datastore structure for use.">ncds_init()</a> that returns datastore's ID which is used in subsequent calls.</li>
<li><b>Accept incoming NETCONF connection</b>.<br/>
 This is done by a single call to <a class="el" href="db/d52/group__session.html#gad0e758dfee764ae9c2a032e0151c6707" title="Accept NETCONF session from a client.">nc_session_accept()</a>. Optionally, specific capabilities supported by the server can be set.</li>
<li><b>Process incoming requests</b>.<br/>
 Use <a class="el" href="db/de9/group__rpc.html#gae7db211326df2358bde428f5e2a80605" title="Receive &lt;rpc&gt; request from the specified NETCONF session. This function is supposed to be performed o...">nc_session_recv_rpc()</a> to get next request from the client from the specified NETCONF session. In case of error return code, the state of the session should be checked by <a class="el" href="db/d52/group__session.html#gacebd018e30c3eeb0638bbb428a1741b4" title="Get information about the session current status.">nc_session_get_status()</a> to get know if the session can be further used.<br/>
 According to the type of the request (<a class="el" href="db/de9/group__rpc.html#gaa502fb30575000775b29a764101c1bef" title="Get type of the rpc message.">nc_rpc_get_type()</a>), perform appropriate action:<ul>
<li><em>NC_RPC_DATASTORE_READ</em> or <em>NC_RPC_DATASTORE_WRITE</em>: use <a class="el" href="db/d67/group__store.html#gaabfd0bf6abeaf40659043bf082e14801" title="Perform requested RPC operation on the datastore.">ncds_apply_rpc()</a> to perform requested operation on the datastore. If the request affects the running datastore (<a class="el" href="db/de9/group__rpc.html#gab240067d45d58c945cdfd61948751379" title="Get target datastore type (running, startup, candidate) of the rpc request.">nc_rpc_get_target()</a> == NC_DATASTORE_RUNNING), apply configuration changes to the controlled device.</li>
<li><em>NC_RPC_SESSION</em>:<dl class="todo"><dt><b><a class="el" href="dd/da0/todo.html#_todo000001">Todo:</a></b></dt><dd>some common function to performi this type of requests will be added.<br/>
</dd></dl>
</li>
</ul>
</li>
<li><b>Reply to the client's request</b>.<br/>
 Reply message is automatically generated by the <a class="el" href="db/d67/group__store.html#gaabfd0bf6abeaf40659043bf082e14801" title="Perform requested RPC operation on the datastore.">ncds_apply_rpc()</a> function. However, server can generate its own replies using <a class="el" href="d0/de2/group__reply.html#ga4789f8372e5f2676236ddb0e6eeb8bb4" title="Create &lt;ok&gt; rpc-reply response.">nc_reply_ok()</a>, <a class="el" href="d0/de2/group__reply.html#ga4543351c89208bb06fa895be334d59ad" title="Create rpc-reply response with &lt;data&gt; content.">nc_reply_data()</a> or <a class="el" href="d0/de2/group__reply.html#ga12fd89263289491b84398279e0e449fd" title="Create rpc-reply response with &lt;rpc-error&gt; content.">nc_reply_error()</a> functions. The reply is sent to the client using <a class="el" href="d0/de2/group__reply.html#ga893dde0156194a5146f5d5ae44558281" title="Send &lt;rpc-reply&gt; response via specified NETCONF session. This function is supposed to be performed on...">nc_session_send_reply()</a> call.</li>
<li><b>Free all unused objects</b>.<br/>
 Do not forget to free received rpc messages (<a class="el" href="db/de9/group__rpc.html#ga4041bda37caa9eedb7a1e2534280f3df" title="Free rpc message.">nc_rpc_free()</a>) and created replies (<a class="el" href="d0/de2/group__reply.html#ga17aa9f38d7b75dec1a57b478b0b39710" title="Free reply message.">nc_reply_free()</a>).</li>
<li><b>Server loop</b>.<br/>
 Repeat previous three steps.</li>
<li><b>Close the NETCONF session</b>.<br/>
 Use functions <a class="el" href="db/d52/group__session.html#ga20b9940ed7af543a05b4bef6e871cedd" title="Close NETCONF connection with the server.">nc_session_close()</a> and <a class="el" href="db/d52/group__session.html#gaa5994f45a7031dc931bdf4a3acebedee" title="Cleanup the session structure and free all allocated resources.">nc_session_free()</a> (in this order) to close and free all used sources and structures connected with the session. Session can be closed by the server according to its internal reasons or by the libnetconf due to some error. In the second case, libnetconf marks the status of the session as non-working (nc_session_get_status != NC_SESSION_STATUS_WORKING).</li>
</ol>
<h2>GLOSSARY</h2>
<ul>
<li><b>message</b> - all types of messages passing through the NETCONF. It includes rpc, rpc-reply and notification. </li>
</ul>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Tue Sep 25 2012 10:18:12 for libnetconf by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.1 </li>
  </ul>
</div>
</body>
</html>
